docs(skills): drop the removed feature_flags settings manifest from plugin-development - #30726

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

Contract-review-claim: session_016WV4d1mkgEris4MHHLjtnk · head 997decb · 2026-11-05T23:38Z

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 997decb3e4e1abd6f71533f246585e3497e2c31b
Local-runs: none
Scope: hits skills/objectstack-platform/references/plugin-development.md + .changeset/30275-plugin-dev-feature-flags-bullet.md; cited on origin/main: packages/services/service-settings/src/index.ts, src/settings-service.ts, src/settings-service-plugin.ts, src/settings-service.types.ts, src/settings-service.test.ts, src/manifests/index.ts, README.md, packages/spec/src/kernel/public-auth-features.ts, docs/adr/0007-settings-manifest-and-kv-store.md, packages/skills/package.json, skills/objectstack-platform/evals/config-plugins-ops.json, AGENTS.md

① Derived judgments

• Net diff against current main (git diff origin/main...997decb3): exactly two files, +12/-3; git log origin/main..997decb3 is the one docs commit 677b6cb2 plus the merge 997decb3, and the merge carries nothing of its own (the three-dot diff is identical to the PR file list). Correct.
• Removed claim: the feature_flags manifest / ai_enabled / beta_* / OS_FEATURE_FLAGS_* bullet (old L354-356). On main that namespace is gone: manifests/index.ts:4-16,29 lists no feature-flags manifest and no featureFlagsSettingsManifest export; settings-service.test.ts:44-60 pins getManifest('feature_flags') to { code: 'SETTINGS_UNKNOWN_NAMESPACE' } with OS_FEATURE_FLAGS_AI_ENABLED: 'true' in env and svc.get('feature_flags','ai_enabled') rejecting (env var inert). PR fix(service-settings)!: remove the Feature Flags page whose four toggles changed nothing #30272 (merged 2026-11-05T05:47Z) removed src/manifests/feature-flags.manifest.ts and the index.ts export. Removal is correct.
• New claim "no shared flags namespace exists": true on main (manifests/index.ts:29 aggregate; settings-service.test.ts:51 asserts builtinSettingsManifests does not contain feature_flags).
• New claim "declares its own SettingsManifest": SettingsManifest is a type re-export from @objectstack/service-settings "so plugin authors only need one import" (src/index.ts:179-182), source @objectstack/spec/system. Correct name.
• New claim "registers it on the settings service": SettingsServicePlugin declares providesServices = ['settings'] (settings-service-plugin.ts:180) and calls ctx.registerService('settings', this.service) (:264); SettingsService.registerManifest(manifest: SettingsManifest): void is a public class method (settings-service.ts:1246) and is the documented plugin API (README.md:12,18: kernel.getService('settings') → registerManifest(manifest)). The reference page already teaches ctx.getService(...) (head L103, L240, L268), so the sentence is coherent with the page. Correct.
• "(ADR-0007 cascade)": docs/adr/0007-settings-manifest-and-kv-store.md:77,98 documents the one-resolver env > tenant > user layering with env highest; the word "cascade" is the old bullet's wording kept, a fair paraphrase. Env override for a plugin's own manifest is generic: envKeyOf(namespace,key) → OS_${NAMESPACE}_${KEY} (settings-service.types.ts:643-646), used at settings-service.ts:1393, so the implied cascade holds for any registered namespace. The new text makes no OS_* claim of its own. Correct.
• Neighbouring bullet (PUBLIC_AUTH_FEATURES, head L356-358) is byte-unchanged and still true: export const PUBLIC_AUTH_FEATURES at packages/spec/src/kernel/public-auth-features.ts:95, requiresFeature lowering documented at :30,304. The bullet's kernel/public-auth-features.ts path is a pre-existing short form of packages/spec/src/kernel/…, not touched by this PR.
• Acceptance 1 met (bullet replaced with the live answer, deployment capability left to the next bullet). Acceptance 2: git grep -i 'feature_flags|OS_FEATURE_FLAGS|ai_enabled' over skills/ at head returns nothing (exit 1); the package's only eval skills/objectstack-platform/evals/config-plugins-ops.json does not mention them, and no eval in any package prompts for feature flags (grep flag|toggle over skills/*/evals/** hits only unrelated automation/UI evals). Acceptance 3: fix(service-settings)!: remove the Feature Flags page whose four toggles changed nothing #30272 is merged and head's text differs from main only by this hunk. Dev's "skills/** grep hits only that bullet" claim verified (on main: plugin-development.md:354,356 only).
• Stale feature_flags mentions remain on main outside skills/** (docs/adr/0007…:230,334, docs/adr/0028…:227, docs/adr/0128…:55, content/docs/releases/v9.mdx:93) — outside this card's file surface (dispatch: skills/** only, ⛔ packages/**), ADRs are historical records; not a finding against this PR.

② Semver level

'@objectstack/skills': patch (.changeset/30275-plugin-dev-feature-flags-bullet.md:2), package exists at packages/skills/package.json. Docs-only edit to a shipped skills reference: patch is the correct level per AGENTS.md:1019-1020 (published package → patch, never skip-changeset). Changeset body carries line-initial Clause-②: no and Metadata-protocol: none (lines 7-8, verified with cat -A), consistent with the PR body (Fixes #30275 / Clause-②: no / Metadata-protocol: none, lines 3-5). Metadata-protocol: none re-derives correctly: nothing under packages/spec/** or any metadata-author-facing key changes. "Check Changeset" check-run: success.

③ Boundary flags

• Dev deviation (relay pr_create HTTP 500 ×3 on 677b6cb2, then merged origin/main and retried → PR docs(skills): drop the removed feature_flags settings manifest from plugin-development #30726 on 997decb3): answered — the merge commit adds no content of its own (①, first bullet); judged on the net diff only.
• Dev open_questions: none. NOT MEASURED check:dual-build-cjs-loads / check:lean-entry-closure (need built dist): acceptable narrowing for a Markdown + changeset diff; CI covers them.
• File-surface pins respected: no SKILL.md, no packages/**, no evals/config-plugins-ops.json touched (PR file list: 2 files).
• Token ratchet: dev reports 3137→3125 (ceiling 3137 unchanged), not re-run here (read-only); the diff is net −1 line / shorter text, so the ratchet cannot have moved up; Lint · docs & code guards will confirm.
• PR author user.login = objectstack-fleet[bot]: no external author to name. PR is draft; skills/** is Tier H (AGENTS.md:271-275): landing waits on the maintainer.
• Head check-runs at 2026-11-05T23:41Z: 0 failed; 9 still in_progress (Test Core 1/8 & 2/8, Lint ×3, Type Check ×4); all completed runs success or skipped. Clause ② of the landing gate ("all green") is not yet satisfiable — record stands, the landing seat must re-read check-runs before enqueue.

④ Design judgment

skills/objectstack-platform/references/plugin-development.md (hunk L354-355): the replacement teaches exactly what a customer agent must do — declare a SettingsManifest, register it on the settings service — using names that resolve on main (①), without inventing an OS_* promise, and leaves the deployment-capability case to the unchanged PUBLIC_AUTH_FEATURES bullet, matching card acceptance 1. The section header's framing ("live toggle surfaces are runtime configuration") still holds for both bullets. Token-negative. No must-fix.

.changeset/30275-plugin-dev-feature-flags-bullet.md: level, declarations and summary correct (②). No must-fix.

should-fix 1 (optional, not blocking): the bullet could name the entry point in one phrase (ctx.getService('settings').registerManifest(...)) so a reader need not infer the method from the service name; README.md:18 is the source. Headroom is 12 tokens, so only if it fits the ratchet.

Implemented-by: claude/project-thread-c57y86
Reviewed-by: session_016WV4d1mkgEris4MHHLjtnk

VERDICT: PASS

domain:skills#1 · os-elon-musk · session_016WV4d1mkgEris4MHHLjtnk

维护者速读

• 改了什么:objectstack-platform 插件开发参考页删掉已不存在的 feature_flags 设置清单(ai_enabled / beta_* / OS_FEATURE_FLAGS_*),改成现行做法:插件需要组织级开关时,自己声明 SettingsManifest 并注册到 settings 服务。
• 为什么改:PR fix(service-settings)!: remove the Feature Flags page whose four toggles changed nothing #30272 已删除该命名空间,getManifest('feature_flags') 现在会被拒;旧文本会让 AI 写出针对不存在命名空间的检查,或让管理员设一个无效的环境变量。
• 风险与回滚:一处技能文档 + changeset,不动代码;回滚即 revert 本 PR。
• 先看:skills/objectstack-platform/references/plugin-development.md 第 354–355 行。
• 两分钟验证:git grep -i feature_flags -- skills/ 应为空。
• 需要你做的:批准并合并(skills/** 为 Tier H)。契约复核 PASS 评论 6672499661,Head-sha 997decb3e4e1abd6f71533f246585e3497e2c31b。
• 席位意见:可合。复核的可选建议(点名 registerManifest(...) 入口)没有做,不值得为它再推一次。

席位核对 — ACCEPT · head 997decb

• 形态:2 文件 +12/−3(参考页一条 + 根 changeset '@objectstack/skills': patch);head 含一次合并 main(无冲突,不带自身内容)。governed skills/**(Tier H)。Fixes #30275,draft,目标 main,作者 objectstack-fleet[bot]。
• 契约:Clause-② no,Metadata-protocol none,与认领 6671821447 一致。
• 前提实测:dev 报告 6672413230;新句子的每个名字都对 service-settings 源码与 README 核过(复核记录 ①)。evals 无 feature_flags 提示,未改。
• 门禁 check-runs:head 上 41 个,28 success,13 skipped,0 红。
• 接受的偏差:无;token 3137→3125,上限未抬。
• 范围外去向:docs/adr/** 与 content/docs/releases/v9.mdx 仍有历史提及,属历史记录,不立卡。
• 落地条款:Tier H,等 governed 审批人批准;批准后席位经中继 pr_ready + automerge_enable,合并后核 skills(objectstack-platform): plugin-development.md still lists a feature_flags settings manifest with ai_enabled / OS_FEATURE_FLAGS_*; PR #30272 removes that namespace #30275 已关、摘 pm:dispatched。